<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 1.5.4">
<title>OpenIEC61850 User Guide</title>
<style>
/*
 * AsciiDoc 'volnitsky' theme for xhtml11 and html5 backends.
 * Based on css from http://volnitsky.com, which was in turn based on default
 * theme from AsciiDoc
 *
 * FIXME: The styling is still a bit rough in places.
 *
 */

/* Default font. */
body {
  font-family: Helvetica, sans-serif;
  max-width:62.5em;
  margin: auto;
}

/* Title font. */

h1, h2, h3, h4, h5, h6 {
    clear: both;
    font-family: Helvetica, serif;
    line-height: 1.3;
}

a {
    border-bottom: 1px dotted #999999;
    color: #378f03 !important;
    text-decoration: none !important;
}
a:hover {
    border-bottom: 1px solid #378f03;
    color: #378f03 !important;
    text-decoration: none !important;
}

em {
  font-style: italic;
  color: #4E4E4E;
}

strong {
  font-weight: bold;
  color: #000000;
}


div.sectionbody {
/*  margin-left: 0;*/
}

hr {
  border: 1px solid #575757;
}


pre {
  padding: 0;
  margin: 0;
}

#author {
  color: #575757;
  font-weight: bold;
  font-size: 1.1em;
}

#footer {
  font-size: small;
  padding-top: 0.5em;
  margin-top: 4.0em;
}

#footer-text {
  float: left;
  padding-bottom: 0.5em;
}

#footer-badges {
  float: right;
  padding-bottom: 0.5em;
}

#preamble {
  margin-top: 1.5em;
  margin-bottom: 1.5em;
}

div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
div.admonitionblock {
  margin-top: 1.5em;
  margin-bottom: 1.5em;
}

div.admonitionblock {
  margin-top: 2.5em;
  margin-bottom: 2.5em;
}

div.content { /* Block element content. */
  padding: 0;
}

/* Block element titles. */
div.title, caption.title {
  color: #575757;
  font-weight: bold;
  text-align: left;
  margin-top: 1.0em;
  margin-bottom: 0.5em;
}
div.title + * {
  margin-top: 0;
}

td div.title:first-child {
  margin-top: 0.0em;
}
div.content div.title:first-child {
  margin-top: 0.0em;
}
div.content + div.title {
  margin-top: 0.0em;
}

div.sidebarblock > div.content {
  background: #ffffee;
  border: 1px solid silver;
  padding: 0.5em;
}

div.listingblock > div.content {
  border: 1px solid silver;
  background: #f4f4f4;
  padding: 0.5em;
}

div.quoteblock {
  padding-left: 2.0em;
  margin-right: 10%;
}
div.quoteblock > div.attribution {
  padding-top: 0.5em;
  text-align: right;
}

div.verseblock {
  padding-left: 2.0em;
  margin-right: 10%;
}
div.verseblock > pre.content {
  font-family: inherit;
}
div.verseblock > div.attribution {
  padding-top: 0.75em;
  text-align: left;
}
/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
div.verseblock + div.attribution {
  text-align: left;
}

div.admonitionblock .icon {
  vertical-align: top;
  font-size: 1.1em;
  font-weight: bold;
  text-decoration: underline;
  color: #575757;
  padding-right: 0.5em;
}
div.admonitionblock td.content {
  padding-left: 0.5em;
  border-left: 2px solid silver;
}

div.exampleblock > div.content {
  border-left: 2px solid silver;
  padding: 0.5em;
}

div.imageblock div.content { padding-left: 0; }
span.image img { border-style: none; }
a.image:visited { color: white; }

dl {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
dt {
  margin-top: 0.5em;
  margin-bottom: 0;
  font-style: normal;
  color: #575757;
}
dd > *:first-child {
  margin-top: 0.1em;
}

ul, ol {
    list-style-position: outside;
}
ol.arabic {
  list-style-type: decimal;
}
ol.loweralpha {
  list-style-type: lower-alpha;
}
ol.upperalpha {
  list-style-type: upper-alpha;
}
ol.lowerroman {
  list-style-type: lower-roman;
}
ol.upperroman {
  list-style-type: upper-roman;
}

div.compact ul, div.compact ol,
div.compact p, div.compact p,
div.compact div, div.compact div {
  margin-top: 0.1em;
  margin-bottom: 0.1em;
}

div.tableblock > table {
  border: 3px solid #575757;
}
thead {
  font-weight: bold;
  color: #575757;
}
tfoot {
  font-weight: bold;
}
td > div.verse {
  white-space: pre;
}
p.table {
  margin-top: 0;
}
/* Because the table frame attribute is overriden by CSS in most browsers. */
div.tableblock > table[frame="void"] {
  border-style: none;
}
div.tableblock > table[frame="hsides"] {
  border-left-style: none;
  border-right-style: none;
}
div.tableblock > table[frame="vsides"] {
  border-top-style: none;
  border-bottom-style: none;
}


div.hdlist {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
div.hdlist tr {
  padding-bottom: 15px;
}
dt.hdlist1.strong, td.hdlist1.strong {
  font-weight: bold;
}
td.hdlist1 {
  vertical-align: top;
  font-style: normal;
  padding-right: 0.8em;
  color: #575757;
}
td.hdlist2 {
  vertical-align: top;
}
div.hdlist.compact tr {
  margin: 0;
  padding-bottom: 0;
}

.comment {
  background: yellow;
}

@media print {
  #footer-badges { display: none; }
}

#toctitle {
  color: #575757;
  font-size: 1.2em;
  font-weight: bold;
  margin-top: 1.0em;
  margin-bottom: 0.1em;
}

div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 { margin-top: 0; margin-bottom: 0; }
div.toclevel1 { margin-top: 0.3em; margin-left: 0; font-size: 1.0em; }
div.toclevel2 { margin-top: 0.25em; margin-left: 2em; font-size: 0.9em; }
div.toclevel3 { margin-left: 4em; font-size: 0.8em; }
div.toclevel4 { margin-left: 6em; font-size: 0.8em; }



.monospaced, tt, div.listingblock > div.content {
  font-family:  Consolas, "Andale Mono", "Courier New", monospace;
  color: #004400;
  background: #f4f4f4;
  max-width: 80em;
  line-height: 1.2em;
}

.paragraph p  {
  line-height: 1.5em;
  margin-top: 1em;
}

/*.paragraph p, li, dd, .content { max-width: 85em; }
.admonitionblock               { max-width: 35em; }*/

div.sectionbody div.ulist > ul > li {
  list-style-type: square;
  color: #aaa;
}
  div.sectionbody div.ulist >  ul > li > * {
    color: black;
    /*font-size: 50%;*/
  }


div.sectionbody div.ulist > ul > li div.ulist > ul > li {
  color: #ccd ;
}
  div.sectionbody div.ulist > ul > li div.ulist > ul > li > * {
    color: black ;
  }

/*
 * html5 specific
 *
 * */

table.tableblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
thead, p.tableblock.header {
  font-weight: bold;
  color: #575757;
}
p.tableblock {
  margin-top: 0;
}
table.tableblock {
  border-width: 3px;
  border-spacing: 0px;
  border-style: solid;
  border-color: #575757;
  border-collapse: collapse;
}
th.tableblock, td.tableblock {
  border-width: 1px;
  padding: 4px;
  border-style: solid;
  border-color: #575757;
}

table.tableblock.frame-topbot {
  border-left-style: hidden;
  border-right-style: hidden;
}
table.tableblock.frame-sides {
  border-top-style: hidden;
  border-bottom-style: hidden;
}
table.tableblock.frame-none {
  border-style: hidden;
}

th.tableblock.halign-left, td.tableblock.halign-left {
  text-align: left;
}
th.tableblock.halign-center, td.tableblock.halign-center {
  text-align: center;
}
th.tableblock.halign-right, td.tableblock.halign-right {
  text-align: right;
}

th.tableblock.valign-top, td.tableblock.valign-top {
  vertical-align: top;
}
th.tableblock.valign-middle, td.tableblock.valign-middle {
  vertical-align: middle;
}
th.tableblock.valign-bottom, td.tableblock.valign-bottom {
  vertical-align: bottom;
}



</style>
<style>
/* Stylesheet for CodeRay to match GitHub theme | MIT License | http://foundation.zurb.com */
/*pre.CodeRay {background-color:#f7f7f8;}*/
.CodeRay .line-numbers{border-right:1px solid #d8d8d8;padding:0 0.5em 0 .25em}
.CodeRay span.line-numbers{display:inline-block;margin-right:.5em;color:rgba(0,0,0,.3)}
.CodeRay .line-numbers strong{color:rgba(0,0,0,.4)}
table.CodeRay{border-collapse:separate;border-spacing:0;margin-bottom:0;border:0;background:none}
table.CodeRay td{vertical-align: top;line-height:1.45}
table.CodeRay td.line-numbers{text-align:right}
table.CodeRay td.line-numbers>pre{padding:0;color:rgba(0,0,0,.3)}
table.CodeRay td.code{padding:0 0 0 .5em}
table.CodeRay td.code>pre{padding:0}
.CodeRay .debug{color:#fff !important;background:#000080 !important}
.CodeRay .annotation{color:#007}
.CodeRay .attribute-name{color:#000080}
.CodeRay .attribute-value{color:#700}
.CodeRay .binary{color:#509}
.CodeRay .comment{color:#998;font-style:italic}
.CodeRay .char{color:#04d}
.CodeRay .char .content{color:#04d}
.CodeRay .char .delimiter{color:#039}
.CodeRay .class{color:#458;font-weight:bold}
.CodeRay .complex{color:#a08}
.CodeRay .constant,.CodeRay .predefined-constant{color:#008080}
.CodeRay .color{color:#099}
.CodeRay .class-variable{color:#369}
.CodeRay .decorator{color:#b0b}
.CodeRay .definition{color:#099}
.CodeRay .delimiter{color:#000}
.CodeRay .doc{color:#970}
.CodeRay .doctype{color:#34b}
.CodeRay .doc-string{color:#d42}
.CodeRay .escape{color:#666}
.CodeRay .entity{color:#800}
.CodeRay .error{color:#808}
.CodeRay .exception{color:inherit}
.CodeRay .filename{color:#099}
.CodeRay .function{color:#900;font-weight:bold}
.CodeRay .global-variable{color:#008080}
.CodeRay .hex{color:#058}
.CodeRay .integer,.CodeRay .float{color:#099}
.CodeRay .include{color:#555}
.CodeRay .inline{color:#000}
.CodeRay .inline .inline{background:#ccc}
.CodeRay .inline .inline .inline{background:#bbb}
.CodeRay .inline .inline-delimiter{color:#d14}
.CodeRay .inline-delimiter{color:#d14}
.CodeRay .important{color:#555;font-weight:bold}
.CodeRay .interpreted{color:#b2b}
.CodeRay .instance-variable{color:#008080}
.CodeRay .label{color:#970}
.CodeRay .local-variable{color:#963}
.CodeRay .octal{color:#40e}
.CodeRay .predefined{color:#369}
.CodeRay .preprocessor{color:#579}
.CodeRay .pseudo-class{color:#555}
.CodeRay .directive{font-weight:bold}
.CodeRay .type{font-weight:bold}
.CodeRay .predefined-type{color:inherit}
.CodeRay .reserved,.CodeRay .keyword {color:#000;font-weight:bold}
.CodeRay .key{color:#808}
.CodeRay .key .delimiter{color:#606}
.CodeRay .key .char{color:#80f}
.CodeRay .value{color:#088}
.CodeRay .regexp .delimiter{color:#808}
.CodeRay .regexp .content{color:#808}
.CodeRay .regexp .modifier{color:#808}
.CodeRay .regexp .char{color:#d14}
.CodeRay .regexp .function{color:#404;font-weight:bold}
.CodeRay .string{color:#d20}
.CodeRay .string .string .string{background:#ffd0d0}
.CodeRay .string .content{color:#d14}
.CodeRay .string .char{color:#d14}
.CodeRay .string .delimiter{color:#d14}
.CodeRay .shell{color:#d14}
.CodeRay .shell .delimiter{color:#d14}
.CodeRay .symbol{color:#990073}
.CodeRay .symbol .content{color:#a60}
.CodeRay .symbol .delimiter{color:#630}
.CodeRay .tag{color:#008080}
.CodeRay .tag-special{color:#d70}
.CodeRay .variable{color:#036}
.CodeRay .insert{background:#afa}
.CodeRay .delete{background:#faa}
.CodeRay .change{color:#aaf;background:#007}
.CodeRay .head{color:#f8f;background:#505}
.CodeRay .insert .insert{color:#080}
.CodeRay .delete .delete{color:#800}
.CodeRay .change .change{color:#66f}
.CodeRay .head .head{color:#f4f}
</style>
</head>
<body class="article toc2 toc-left">
<div id="header">
<h1>OpenIEC61850 User Guide</h1>
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="#_distribution">1. Distribution</a></li>
<li><a href="#_sample_client_server">2. Sample Client &amp; Server</a></li>
<li><a href="#_modifying_and_compiling_openiec61850">3. Modifying and Compiling OpenIEC61850</a></li>
<li><a href="#_association">4. Association</a>
<ul class="sectlevel2">
<li><a href="#_client_development">4.1. Client development</a></li>
<li><a href="#_server_development">4.2. Server development</a></li>
</ul>
</li>
<li><a href="#_data_model">5. Data Model</a>
<ul class="sectlevel2">
<li><a href="#_development">5.1. Development</a></li>
</ul>
</li>
<li><a href="#_data_sets">6. Data Sets</a></li>
<li><a href="#_reporting">7. Reporting</a></li>
<li><a href="#_terminology">8. Terminology</a></li>
<li><a href="#_authors">9. Authors</a></li>
</ul>
</div>
</div>
<div id="content">
<div class="sect1">
<h2 id="_distribution">1. Distribution</h2>
<div class="sectionbody">
<div class="paragraph">
<p>OpenIEC61850 consists of the following library components all licensed
under the Apache 2.0 license:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><strong>openiec61850</strong> - is the core implementation of the OpenIEC61850
client and server library (depends on josistack).</p>
</li>
<li>
<p><strong>josistack</strong> - implements the Application Control Service Element
(ACSE) protocol as defined by ISO 8650 or ITU X.217/X.227, the
lower ISO Presentation Layer as defined by ISO 8823/ITU X226, and
the ISO Session Layer as defined by 8327/ITU X.225. The library depends on
jositransport.</p>
</li>
<li>
<p><strong>jositransport</strong> - implements RFC 1006 and the
OSI Transport Service Layer. It is not part of the core library so
it can be used separately by other projects.</p>
</li>
<li>
<p><strong>openiec61850-sample</strong> - implements a sample client and server. This
library/project only exists for demonstration purposes. It shows
you how to create your own client and/or server applications that
use OpenIEC61850.</p>
</li>
<li>
<p><strong>openiec61850-clientgui</strong> - is a graphical user interface for the
client library. It can be used to connect to server browse the
server device model and read and write data. (depends on
openiec61850).</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>After extracting the distribution tar file the OpenIEC61850 libraries
can be found in the build/libs-all folder. Besides the libraries mentioned
above it contains the following external libraries:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><strong>jasn1</strong> - a library from the jASN1 project doing BER
encoding/decoding (needed by the openiec61850 and josistack
libraries), Copyright 2011-14 Fraunhofer ISE, Author: Stefan
Feuerhahn, License: LGPLv2.1 or later, <a href="http://www.openmuc.org" class="bare">http://www.openmuc.org</a></p>
</li>
<li>
<p><strong>slf4j-api</strong> - a popular logging API, License: MIT,
<a href="http://www.slf4j.org" class="bare">http://www.slf4j.org</a></p>
</li>
<li>
<p><strong>logback-core/logback-classic</strong> - an actual logger implementation of
the slf4-api. openiec61850-sample uses it to output log
information. It can be replaced by a logger of your choice that
supports the slf4j API. License: EPLv1.0 and LGPLv2.1,
<a href="http://logback.qos.ch" class="bare">http://logback.qos.ch</a></p>
</li>
<li>
<p><strong>jcalendar</strong> - a calendar library needed by the client GUI. &#169;
1999-2011 Kai Toedter, License: LGPLv3,
<a href="http://toedter.com/jcalendar/" class="bare">http://toedter.com/jcalendar/</a></p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_sample_client_server">2. Sample Client &amp; Server</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The easiest way to learn how OpenIEC61850 works is by getting the
sample client and server applications running. Then you might want to
look at the source code of the sample applications to get an
understanding of how they work.</p>
</div>
<div class="paragraph">
<p>The sample client and sample server can be used as a basis for you to
code your individual client or server applications.</p>
</div>
<div class="paragraph">
<p>You can execute the sample client and server through the scripts found
in the folder <em>run-scripts</em>.  Executing the script without any
parameters will print help information to the screen. Note that under
Unix/Linux you need root privilages if you want the server to listen
on any port lower than 1000.</p>
</div>
<div class="paragraph">
<p>Instead of running the sample applications from the terminal you can
create Eclipse project files as explained in our
<a href="https://www.openmuc.org/faq/gradle_getting_started/">FAQs</a> and run
them from within Eclipse.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_modifying_and_compiling_openiec61850">3. Modifying and Compiling OpenIEC61850</h2>
<div class="sectionbody">
<div class="paragraph">
<p>We use the Gradle build automation tool. The distribution contains a
fully functional gradle build file (<em>build.gradle</em>). Thus if you
changed code and want to rebuild a library you can do it easily with
Gradle. Also if you want to import our software into Eclipse you can
easily create Eclipse project files using Gradle. Just follow the
instructions on our
<a href="https://www.openmuc.org/faq/gradle_getting_started/">FAQ site</a>.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_association">4. Association</h2>
<div class="sectionbody">
<div class="paragraph">
<p>An IEC 61850 device that is to be controlled or monitored is called an
IEC 61850 server. An IEC 61850 server normally listens on port 102 for
incoming connection requests by IEC 61850 clients.</p>
</div>
<div class="sect2">
<h3 id="_client_development">4.1. Client development</h3>
<div class="paragraph">
<p>If you want to connect to an IEC 61850 server, you should first create
an instance of ClientSap (SAP = Service Access Point) and configure it
to your needs. Then you build up the association to the server using
the associate() method.</p>
</div>
</div>
<div class="sect2">
<h3 id="_server_development">4.2. Server development</h3>
<div class="paragraph">
<p>First get a List of ServerSaps using the method
ServerSap.getSapsFromSclFile(). This method reads in the SAP from the
given ICD file. Take the ServerSap you want to run and configure it to
your needs (e.g. set the port to listen on). The ServerSap includes
the complete device model defined in the ICD file. Retrieve a copy of
it using the method getModelCopy(). Tell the ServerSap to start
to listen on the configured port using startListening(). This is a
non-blocking function.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_data_model">5. Data Model</h2>
<div class="sectionbody">
<div class="paragraph">
<p>An IEC 61850 server contains a treelike data model that contains at
its leafs the data (integers, boolean, strings etc) that can be
accessed by clients. Clients can also retrieve the whole data model
from the server.</p>
</div>
<div class="paragraph">
<p>The upper most model node ist called "server". In OpenIEC61850 it is
an object of type ServerModel. The server node contains 1..n logical
devices (LD). A logical device may contain 1..n logical nodes (LN). A
logical node may contain 1..n data objects. In OpenIEC61850 the
logical nodes do not contain complete data objects but instead contain
so called functionally constraint data objects (FCDO). An FCDO is a
data object that is split up by functional constraint. An FCDO can
contain a combination of other FCDOs, arrays, constructed data
attributes and/or basic data attributes.</p>
</div>
<div class="paragraph">
<p>All nodes of the server model in OpenIEC61850 are of one of the
following seven types:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>ServerModel</p>
</li>
<li>
<p>LogicalDevice</p>
</li>
<li>
<p>LogicalNode</p>
</li>
<li>
<p>FcDataObject</p>
</li>
<li>
<p>Array</p>
</li>
<li>
<p>ConstructedDataAttribute</p>
</li>
<li>
<p>BasicDataAttribute</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>They all implement the ModelNode interface. The nodes FcDataObject,
Array, ConstructedDataAttribute and BasicDataAttribute also implement
the interface called FcModelNode because they are considered
functionally constraint data in the standard. Many of the services of
IEC 61850 can only be applied to functionally constraint data
(e.g. GetDataValues and SetDataValues).</p>
</div>
<div class="sect2">
<h3 id="_development">5.1. Development</h3>
<div class="paragraph">
<p>When programming a client you get a copy of the server model either
through ClientAssociation.retrieveModel() or
ClientAssociation.getModelFromSclFile(). When programming a server you
get a copy of the server model through the ServerSap.getModelCopy()
function.</p>
</div>
<div class="paragraph">
<p>You can then navigate through the model using several functions:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>ServerModel.findModelNode(ObjectReference objectReference, Fc fc)
will search for the subnode with the given reference and functional
constraint.</p>
</li>
<li>
<p>ModelNode.getChild(String name, Fc fc) will return the child node
with the given name and functional constraint.</p>
</li>
<li>
<p>ModelNode.getBasicDataAttributes() will return a list of all leaf
nodes (basic data attributes) of the model node.</p>
</li>
</ul>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_data_sets">6. Data Sets</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Data sets (DS) form a group/set of data. Data sets can be used to read
or write several data objects/data attributes at once using a single
request/response message exchange. The service used for this are
GetDataSetValues and SetDataSetValues. Besides the data set
services the reporting, logging, GOOSE and sampled value services also
use the data set concept.</p>
</div>
<div class="paragraph">
<p>The data attributes or data objects that are part of a data set are
called the members of a data set. Only functionally constraint data
may be a member of a data set.</p>
</div>
<div class="paragraph">
<p>The IEC 61850 standard defines five ASCI services related to data sets:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><strong>GetDataSetValues</strong> to get the value of all members of the data set.</p>
</li>
<li>
<p><strong>SetDataSetValues</strong> to set the value of all members of the data set.</p>
</li>
<li>
<p><strong>CreateDataSet</strong> to create a new data set dynamically.</p>
</li>
<li>
<p><strong>DeleteDataSet</strong> to delete a data set that was created.</p>
</li>
<li>
<p><strong>GetDataSetDirectory</strong> to get the list of all existing data sets in
the server</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Two types of data sets exist:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><strong>Persistent data sets</strong> - they have a reference of the format
LDName/LNName.DataSetName . They are visible to all
clients. Persistent data sets can be preconfigured in the SCL
file. In this case they cannot be deleted. Persistent data sets can
also be dynamicall created by clients. In this case they may be
deleted again later. Dynamically created data sets will be
automatically deleted once the server stops.</p>
</li>
<li>
<p><strong>Non-persistent data sets</strong> - they have a reference of the format
@datasetname . They are only visible to the client that created it
through the CreateDataSet service. These data sets only exist as
long as the association is open.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_reporting">7. Reporting</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Reporting allows a server to send data based on events and without
explict request by the client. What data is sent and the events that
cause reports are configured through so called report control blocks
(RCB).</p>
</div>
<div class="paragraph">
<p>The standard distinguishes between two types of reporting: buffered
reporting and unbuffered reporting. With buffered reporting reports
are buffered by the server in case a connection to the client is
interrupted. This way reports can be sent after the client has
connected again. Buffered reporting is configured through buffered
report control blocks (BRCB). Unbuffered reporting is configured
through unbuffered report control blocks (URCB).</p>
</div>
<div class="paragraph">
<p>RCBs are located within logical nodes of the server&#8217;s data model
(i.e. the server&#8217;s ICD/SCL file). They are fixed and cannot be deleted
or added at runtime. An RCB is blocked once a client has registered to
receive reports (by enabling it). That means a single RCB cannot send
reports to several clients in parallel.</p>
</div>
<div class="paragraph">
<p>RCBs are always associated with a specific <a href="#_data_sets">data set</a>
that must be located in the same logical node as the RCB. A subset of
the data set&#8217;s members will be reported if any of the configured
events occures. The associated data set of the RCB can be
dynamically changed by a client at run-time.</p>
</div>
<div class="paragraph">
<p>RCBs are located in logical nodes in the server&#8217;s model tree. Therefor
the reference of an RCB is of the form
LogicalDeviceName/LogicalNodeName.RCBName . Even though RCBs can only
reference data sets located in the same logical node as the RCB
itself, they can still monitor data from other logical nodes because
the data set&#8217;s members can be located in other logical nodes.</p>
</div>
<div class="paragraph">
<p>The following events can cause a server to send a report:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>The client issues a general interrogation.</p>
</li>
<li>
<p>A data attribute that is part of the associated data set changes or
is updated.</p>
</li>
<li>
<p>Periodic sending of reports has been enabled by setting the
integrity period of an RCB.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>Whether one of these events really causes a report to be sent is
configured through the RCB.</p>
</div>
<div class="paragraph">
<p>A report control block contains the following fields:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Configuration fields. They can only be written if the RCB has not
been enabled nor reserved by another client:</p>
<div class="ulist">
<ul>
<li>
<p><strong>RptID</strong> - The report ID identifies the RCB. If not set, it equals
the RCB reference. The RptID will be sent with every report so that
the client can identify the RCB responsible for the report.</p>
</li>
<li>
<p><strong>DatSet</strong> - The reference of the data set associated with this RCB. It
must be located in the same logical node as the RCB. Members of
this data set will be reported whenever the configured events
occure.</p>
</li>
<li>
<p><strong>OptFlds</strong> - A bitstring where each bit indicates whether an
optional field is included in the reports caused by this RCB. The
following optional fields exist: sequence-number, report-
timestamp, reason-for-inclusion, data-set-name, data-reference,
buffer-overflow, entryID, segmentation, and conf-revision. For
URCBs the values of buffer-overflow and entryID are ignored.</p>
</li>
<li>
<p><strong>BufTm</strong> - In case of an event that causes a report the server will
wait for <em>BufTm</em> ms for other events. All data that is to be
reported because of events in this time span is sent in a single
report.</p>
</li>
<li>
<p><strong>TrgOps</strong> - Specifies which events will trigger reports. Possible
events are:</p>
<div class="ulist">
<ul>
<li>
<p>data change (dchg)</p>
</li>
<li>
<p>quality change (qchg)</p>
</li>
<li>
<p>data update (dupd)</p>
</li>
<li>
<p>integrity - if enabled the server will send periodic integrity
reports to the client. Integrity reports will contain the current
values of all members of the referenced data set.</p>
</li>
<li>
<p>general interrogation (GI).</p>
</li>
</ul>
</div>
</li>
<li>
<p><strong>IntgPd</strong> - The integrity period specifies an interval in ms for the
periodic sending of intergrity reports.</p>
</li>
<li>
<p><strong>PurgeBuf</strong> (only part of BRCBs not URCBs) -</p>
</li>
<li>
<p><strong>EntryID</strong> (only part of BRCBs not URCBs) -</p>
</li>
</ul>
</div>
</li>
<li>
<p>Information fields: can only be read:</p>
<div class="ulist">
<ul>
<li>
<p><strong>SqNum</strong> - the current sequence number of the RCB. After sending a
report the RCB will increment the sequence number by one.</p>
</li>
<li>
<p><strong>ConfRev</strong> - The configuration revision is a counter representing the number of
times the referenced data set was changed.</p>
</li>
<li>
<p><strong>Owner</strong> - Shall be equal to the IP of the client that reserved the
RCB. Shall be NULL (i.e. the empty string) if the RCB is not
reserved.</p>
</li>
<li>
<p><strong>TimeOfEntry</strong> (only part of BRCBs not URCBs)</p>
</li>
</ul>
</div>
</li>
<li>
<p>Functional fields: The following fields of the RCB can be read or
written to execute functions:</p>
<div class="ulist">
<ul>
<li>
<p><strong>Resv</strong> (only part of URCBs not BRCBs) - Before doing anything with
an RCB a client should reserve it by setting this field to
true. If the setting was successful the RCB will be reserved
exclusively for this client. Enabling an RCB that has not been
reserved implicitly reserves it.</p>
</li>
<li>
<p><strong>ResvTms</strong> (only part of BRCBs not URCBs) - This attribute of BRCBs
is optional. If not present the control block is reserved by
simply enabling it. A ResvTms value of -1 indicates that the
control block was reserved by configuration for a certain set of
clients. A value of 0 indicates that the BRCB is not reserved. A
client can reserve the control block by writing a value largen
than 0. The value represents the number of seconds that the
reservation shall be maintained after the association was closed
or interrupted.</p>
</li>
<li>
<p><strong>RptEna</strong> - By setting this variable to true reporting will be
enabled. Note that changing/writing and configuration fields of
the RCB will fail as long as reporting is enabled.</p>
</li>
<li>
<p><strong>GI</strong> - General Interrogation. Setting this parameter to true will
initiate a report to be sent to the client. This report will
contain all the data of the associated data set. The GI parameter
will be reset to false automatically by the server once the report
has been sent.</p>
</li>
</ul>
</div>
</li>
</ul>
</div>
<div class="paragraph">
<p>A report always contains the following information fields:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><strong>RptID</strong> - The report ID identifies the RCB that has caused the
generation of the report. It equals the RptID field of the RCB.</p>
</li>
<li>
<p><strong>OptFlds</strong> - It is equal to the OptFlds field of the corresponding
RCB.</p>
</li>
<li>
<p><strong>SqNum</strong> (optional, included if OptFlds.SequenceNumber is true) - The
sequence number of the report. It is equal to the SqNum field of
the corresponding RCB by the time it was sent.</p>
</li>
<li>
<p><strong>TimeOfEntry</strong> (optional, included if OptFlds.report-timestamp is
true) - specifies the time when the Entry ID was created.</p>
</li>
<li>
<p><strong>DatSet</strong> (optional, included if OptFlds.dataset-name is true) - The
reference of the data set whose data is sent in this report.</p>
</li>
<li>
<p><strong>BufOvfl</strong> (optional, only included if it is a buffered report and
OptFlds.buffer-overflow is true) - Indicates the server lost report
entries due to a buffer overflow. Only applies to buffered
reporting.</p>
</li>
<li>
<p><strong>EntryID</strong> (optional, only included if it is a buffered report and
OptFlds.entryID is true) - Entry identification ToDo</p>
</li>
<li>
<p><strong>ConfRev</strong> (optional, only included if OptFlds.conf-rev is true) - It
is equal to the ConfRev field of the corresponding RCB.</p>
</li>
<li>
<p><strong>SubSqNum</strong> (optional, included if OptFlds.segmentation is true) - In
case that a long report does not fit into one message, a single
report shall be divided into subreports.  Each subreport shall have
the same sequence number and a unique SubSqNum.</p>
</li>
<li>
<p><strong>MoreSegmentsFollow</strong> (optional, included if OptFlds.segmentation is
true) - indicates that more subreports with the same SqNum follow.</p>
</li>
<li>
<p><strong>Inclusion Bitstring</strong> - A bit string whose length equals the number
of data members of the referenced data set. Each bit indicates
whether the corresponding data member is included in the report or
not.</p>
</li>
<li>
<p><strong>Data-references</strong> (optional, included if OptFlds.data-reference is
true) - The references of the reported data set members.</p>
</li>
<li>
<p><strong>Values</strong> - The values of the reported data set members.</p>
</li>
<li>
<p><strong>Reason Codes</strong> (optional, included if OptFlds.reason-for-inclusion
is true) - The reason codes indicate for each reported value, the
reason why it was reported. Possible reasons are data change,
quality change, data update, integrity, general interrogation,
and application trigger. Several reasons can be true for a single
reported value.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>A client that wants to receive reports from a certain RCB would
usually first attempt to reserve the RCB. If successful he would then
configure the RCB as he wishes. Finally he would enable reporting.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_terminology">8. Terminology</h2>
<div class="sectionbody">
<div class="ulist">
<ul>
<li>
<p><strong>BRCB</strong> - Buffered Report Control Block</p>
</li>
<li>
<p><strong>DS</strong> - Data Set</p>
</li>
<li>
<p><strong>LD</strong> - Logical Device</p>
</li>
<li>
<p><strong>LN</strong> - Logical Node</p>
</li>
<li>
<p><strong>SAP</strong> - Service Access Point</p>
</li>
<li>
<p><strong>URCB</strong> - Unbuffered Report Control Block</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_authors">9. Authors</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Developers:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Stefan Feuerhahn</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Former developers:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Claus Brunzema</p>
</li>
<li>
<p>Bertram Lückehe</p>
</li>
<li>
<p>Chau Do</p>
</li>
<li>
<p>Tobias Weidelt</p>
</li>
<li>
<p>Michael Zillgith</p>
</li>
</ul>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
Last updated 2017-01-17 17:03:47 +01:00
</div>
</div>
</body>
</html>